home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / lib / linuxdoc-sgml / doc / guide.sgml < prev    next >
SGML Document  |  1994-06-21  |  32KB
  1. <!-- This is a linuxdoc-sgml User's Guide, by Matt Welsh
  2.      See guide.txt or guide.dvi for formatted output.
  3.      (You need to read this before you can format the source!)
  4. -->
  5.  
  6. <!doctype linuxdoc system>
  7.  
  8. <article>
  9.  
  10. <title>Linuxdoc-SGML User's Guide
  11. <author>Matt Welsh, <tt/mdw@sunsite.unc.edu/
  12. <date>v1.3, 7 June 1994
  13. <abstract>
  14. This document is a user's guide to the linuxdoc-sgml formatting system,
  15. an SGML-based text formatter which allows you to produce LaTeX, plain
  16. ASCII, and HTML from a single source format. This guide documents
  17. Linuxdoc-SGML version 1.1.
  18. </abstract>
  19.  
  20. <toc>
  21.  
  22. <sect>Introduction
  23.  
  24. <p>
  25. This is a user's guide to the <tt/linuxdoc-sgml/ document
  26. processing system, for use with Linux documentation. <tt/linuxdoc-sgml/
  27. is an SGML DTD (Document Type Definition) and set of ``replacement files''
  28. which convert the SGML to <tt/groff/, LaTeX, and HTML source. In the future,
  29. <tt/linuxdoc-sgml/ will support <tt/texinfo/, as well as other
  30. formats. 
  31.  
  32. <tt/linuxdoc-sgml/ is based heavily on the QWERTZ DTD by Tom Gordon,
  33. <tt/thomas.gordon@gmd.de/. I have only made revisions to his DTD and
  34. replacement files for use by Linux documentation. 
  35.  
  36. <tt/linuxdoc-sgml/ is not meant to be a general document-processing system.
  37. Although it can be used for documents of many types, I have tailored it for
  38. use by the Linux documentors in producing HOWTOs, FAQs, and (later) the
  39. Linux Documentation Project manuals. Therefore, I have tweaked features
  40. into and out of the system for this purpose. If you see a lack of generality
  41. in the system, that is the reason. There's nothing binding <tt/linuxdoc-sgml/
  42. to Linux documentation, but all documents produced by the system will look
  43. a certain way. If you want things to look differently I suggest that you use
  44. a more generalized system such as the plain QWERTZ DTD.
  45.  
  46. One of the goals of this system is to make documents easy to produce in
  47. numerous formats. Until now, most Linux documentation has been produced
  48. in plain ASCII through manual editing. A system like <tt/groff/ can take care
  49. of the plain-text formatting, but that still doesn't give you HTML (for
  50. use on the World Wide Web), LaTeX (for nicely printed documents), or
  51. <tt/texinfo/. Therefore, if there are features missing from this system 
  52. that you would like, <em/please let me know!/ The idea is that we shouldn't
  53. have to use a lot of hackery to produce good-looking docs in multiple formats.
  54. The author should have to do as little as possible.
  55.  
  56. <sect1>About this document
  57.  
  58. <p>
  59. This document is written using the <tt/linuxdoc-sgml/ DTD. It contains
  60. more or less everything you need to know to write SGML docs with this
  61. DTD. See <tt/example.sgml/ for an example of an SGML document that you
  62. can use as a model for your own docs.
  63.  
  64. <sect1>Why SGML?
  65.  
  66. <p>
  67. I chose SGML for this system because SGML is made specifically for translation
  68. to other formats. SGML, which stands for Standard Generalized Markup Language,
  69. allows you to specify the <em/structure/ of a document---that is, what kinds
  70. of things make up the document. You specify the structure of a document with
  71. a DTD (Document Type Definition). <tt/linuxdoc-sgml/ is one DTD that specifies
  72. the structure for Linux HOWTOs and other docs. QWERTZ is another DTD; the
  73. SGML standard provides DTD's for books, articles, and other generic document
  74. types.
  75.  
  76. The DTD specifies the names of ``elements'' within the document. An element
  77. is just a bit of structure---like a section, a subsection, a paragraph,
  78. or even something smaller like <em/emphasised text/. Unlike LaTeX, however,
  79. these elements are not in any way intrinsic to SGML itself. The
  80. <tt/linuxdoc-sgml/ DTD happens to define elements that look a lot like 
  81. their LaTeX counterparts---you have sections, subsections, verbatim
  82. ``environments'', and so forth. However, using SGML you can define any kind
  83. of structure for the document that you like. In a way, SGML is like 
  84. low-level TeX, while the <tt/linuxdoc-sgml/ DTD is like LaTeX.
  85.  
  86. Don't be confused by this analogy. SGML is <em/not/ a text-formatting system.
  87. There is no ``SGML formatter'' per se. SGML source is <em/only/ converted
  88. to other formats for processing. Furthermore, SGML itself is used only to 
  89. specify the document structure. There are no text-formatting facilities or
  90. ``macros'' intrinsic to SGML itself. All of those things are defined within
  91. the DTD. You can't use SGML without a DTD---a DTD defines what SGML does.
  92.  
  93. <sect1>How it works
  94.  
  95. <p>
  96. Here's how processing a document with SGML and the <tt/linuxdoc-sgml/ DTD 
  97. works. First, you need a DTD. I'm using the QWERTZ DTD which was produced,
  98. originally, by a group of people who needed a LaTeX-like DTD. I've modified
  99. the QWERTZ DTD to produce the <tt/linuxdoc-sgml/ DTD for our purposes. 
  100. The DTD simply sets up the structure of the document. A small portion of
  101. it looks like this:
  102. <tscreen><verb>
  103. <!element article - -
  104.         (titlepag, header?, 
  105.          toc?, lof?, lot?, p*, sect*, 
  106.          (appendix, sect+)?, biblio?) +(footnote)>
  107. </verb></tscreen>
  108. This part sets up the overall structure for an ``article'', which is like
  109. a ``documentstyle'' within LaTeX. The article consists of a titlepage
  110. (<tt/titlepag/), an optional header (<tt/header/), an optional table of 
  111. contents (<tt/toc/), optional lists of figures (<tt/lof/) and tables
  112. (<tt/lot/), any number of paragraphs (<tt/p/), any number of top-level
  113. sections (<tt/sect/), optional appendices (<tt/appendix/), an optional
  114. bibliography (<tt/biblio/) and footnotes (<tt/footnote/). 
  115.  
  116. As you can see, the DTD doesn't say anything about how the document should
  117. be formatted or what it should look like. It just defines what parts make
  118. up the document. Elsewhere in the DTD the structure of the 
  119. <tt/titlepag/, <tt/header/, <tt/sect/, and other elements are defined. 
  120.  
  121. You don't need to know anything about the syntax of
  122. the DTD in order to write documents. I'm just presenting it so you know
  123. what it looks like and what it does. You <em/do/ need to be familiar with
  124. the document <em/structure/ that the DTD defines. If not, you might
  125. violate the structure when attempting to write a document, and be very
  126. confused about the resulting error messages. We'll describe the
  127. structure of <tt/linuxdoc-sgml/ documents in detail later.
  128.  
  129. The next step is to write a document using the structure defined by the
  130. DTD. Again, the <tt/linuxdoc-sgml/ DTD makes documents look a lot like
  131. LaTeX---it's very easy to follow. In SGML jargon a single document written
  132. using a particular DTD is known as an ``instance'' of that DTD. 
  133.  
  134. In order to translate the SGML source into another format (such as LaTeX
  135. or nroff) for processing, the SGML source (the document that you wrote)
  136. is <em/parsed/ along with the DTD by (you guessed it) the SGML <em/parser/.
  137. I'm using the <tt/sgmls/ parser by James Clark, <tt/jjc@jclark.com/, who
  138. also happens to be the author of <tt/groff/. We're in good hands.
  139. The parser (the executable <tt/sgmls/ simply picks through your document and 
  140. verifies that it follows the structure set forth by the DTD. It also spits out
  141. a more explicit form of your document, with all ``macros'' and elements
  142. expanded, which is understood by <tt/sgmlsasp/, the next part of the
  143. process. 
  144.  
  145. <tt/sgmlsasp/ is responsible for converting the output of <tt/sgmls/ to
  146. another format (such as LaTeX). It does this using <em/replacement files/,
  147. which describe how to convert elements in the original SGML document into
  148. corresponding source in the ``target'' format (such as LaTeX or <tt/nroff/). 
  149.  
  150. For example, part of the replacement file for LaTeX looks like:
  151. <tscreen><verb>
  152. <itemize>       +       "\\begin{itemize}"      +
  153. &etago;itemize>      +       "\\end{itemize}"        +
  154. </verb></tscreen>
  155. Which says that whenever you begin an <tt/itemize/ element in the 
  156. SGML source, it should be replaced with 
  157. <tscreen><verb>
  158. \begin{itemize}
  159. </verb></tscreen>
  160. in the LaTeX source. (As I said, elements in the <tt/linuxdoc-sgml/ DTD
  161. are very similar to their LaTeX counterparts). 
  162.  
  163. So, to convert the SGML to another format, all you have to do is write
  164. a new replacement file for that format that gives the appropriate 
  165. analogues to the SGML elements in that new format. In practice, it's not
  166. that simple---for example, if you're trying to convert to a format that
  167. isn't structured at all like your DTD, you're going to have trouble. In 
  168. any case, it's much easier to do than writing individual parsers and
  169. translators for many kinds of output formats; SGML provides a generalized
  170. system for converting one source to many formats.
  171.  
  172. Once <tt/sgmlsasp/ has completed its work, you have LaTeX source which
  173. corresponds to your original SGML document, which you can format using
  174. LaTeX as you normally would. Later in this document I'll give examples
  175. and show the commands used to do the translation and formatting. You can
  176. do this all on one command line.
  177.  
  178. But first, I should describe how to install and configure the software.
  179.  
  180. <sect>Installation
  181. <p>
  182. The file <tt/linuxdoc-sgml.tar.gz/ contains everything that you need
  183. to write SGML documents and convert them to LaTeX, nroff, and HTML. 
  184. In addition to this package, you will need one or both of the following:
  185. <enum>
  186. <item><tt/groff/. You <em/need/ version 1.08 or 1.09. Apparently some of
  187. the margin-handling in <tt/groff/ is in a state of flux from version to
  188. version; they both work, but you get slightly different results. 
  189. (Particularly, with 1.09 the left margin isn't indented two characters as 
  190. it is in 1.08. There is a way around it, but it looks terrible on 1.08.
  191. Versions previous to 1.08 <em/will not work/. 
  192. You can get this from <tt/prep.ai.mit.edu/ in 
  193. <tt>/pub/gnu</tt>. There is a Linux binary version on <tt/sunsite/ as well.
  194. You will need <tt/groff/ to produce plain ASCII from your SGML docs.
  195. (TeX/LaTeX will be used to produce nicely-printed PostScript and .dvi). 
  196.  
  197. <item>TeX and LaTeX. This is available more or less everywhere; you should
  198. have no problem getting it and installing it (there is a Linux binary
  199. distribution on <tt/sunsite/). Of course, you only need TeX/LaTeX
  200. if you want to format your SGML docs with LaTeX. So, installing TeX/LaTeX
  201. is optional. See the section on the Linux HOWTO project below for how we'll
  202. manage this vis-a-vis the Linux HOWTOs. 
  203.  
  204. <item>If you want to view the generated HTML, I suggest getting NCSA Mosaic
  205. 2.2 or later.
  206.  
  207. </enum>
  208. Neither of these are required by the SGML system, but I suggest that you get
  209. one or the other in order to format your docs and verify that they look 
  210. all right before distributing them. 
  211.  
  212. <sect1>Installing the software
  213.  
  214. <p>
  215. The steps needed to install and configure the <tt/linuxdoc-sgml/ stuff are
  216. as follows:
  217.  
  218. <enum>
  219. <item>First, unpack the tar file <tt/linuxdoc-sgml.tar.gz/ somewhere. 
  220. This will create the directory <tt/linuxdoc-sgml/ where all of the SGML
  221. files live. It doesn't matter where you unpack this file; just don't
  222. move things around within the <tt/linuxdoc-sgml/ directory.
  223.  
  224. <item>Next, you need to compile the <tt/sgmls/ parser. In the
  225. <tt>linuxdoc-sgml/sgmls-1.1</tt> directory, issue the commands:
  226. <tscreen><verb>
  227. $ make config.h
  228. $ make
  229. $ make install
  230. $ make install.man
  231. </verb></tscreen>
  232. This should compile the parser and translator, and place the binaries
  233. <tt/sgmls/, <tt/sgmlsasp/, and <tt/rast/ in <tt>linuxdoc-sgml/bin</tt>.
  234. I suggest that you don't move those binaries from that location; instead,
  235. make symlinks to them from <tt>/usr/local/bin</tt> or place
  236. <tt>linuxdoc-sgml/bin</tt> on your path. (If you move things around
  237. within the <tt/linuxdoc-sgml/ tree you'll have to edit a number of files
  238. to get everything to cooperate again. Best to leave things as-is.) 
  239.  
  240. If things don't work try editing the <tt/Makefile/ in the <tt/sgmls-1.1/
  241. directory. I have it set to use <tt/gcc/ as the compiler, and use
  242. rather malignant options. Compiles fine on Linux and sun-4 systems.
  243.  
  244. This will also install man pages for the three binaries in 
  245. <tt>linuxdoc-sgml/man</tt>. You can move those or link them to your
  246. regular man page tree, should you need them.
  247.  
  248. <item>Edit the variables at the top of the scripts <tt/format/, <tt/qroff/,
  249. <tt/preroff/, <tt/prehtml/, and <tt/qtex/ in <tt>linuxdoc-sgml/bin</tt>. 
  250. All you really need to edit is the value of the <tt>LINUXDOC</tt> 
  251. shell variable which gives the full pathname of the <tt>linuxdoc-sgml</tt>
  252. directory.
  253.  
  254. <item>In the <tt>html-fix</tt> directory, issue the commands:
  255. <tscreen><verb>
  256. $ make
  257. $ make install
  258. </verb></tscreen>
  259. This will build <tt>fixref</tt> and <tt>html2html</tt>, which are post
  260. processors for the HTML conversion, and place them in the <tt>bin</tt>
  261. directory.
  262.  
  263. </enum>
  264.  
  265. If all went well, you should be ready to use the system. Just be sure
  266. that <tt>linuxdoc-sgml/bin</tt> is on your path or you've linked the 
  267. files therein to your standard binary directories. Again, don't just copy 
  268. them somewhere else; the scripts expect to find each other in that
  269. directory.
  270.  
  271. <sect1>Testing it out
  272.  
  273. <p>
  274. You can now test the system. The <tt/format/ script takes an SGML
  275. document as input and translates it to a given format. The <tt/qtex/
  276. script will process the output of <tt/format/ using LaTeX, and 
  277. <tt/qroff/ will process it using nroff.
  278.  
  279. Let's say you have the SGML document <tt/foo.sgml/. You can translate
  280. it to LaTeX, and produce PostScript output (via <tt/dvips/) with
  281. the command:
  282. <tscreen><verb>
  283. $ format -Tlatex foo | qtex > foo.ps
  284. </verb></tscreen>
  285. Or, you can produce a DVI file using the <tt>-d</tt> switch with 
  286. <tt>qtex</tt>, as so:
  287. <tscreen><verb>
  288. $ format -Tlatex foo | qtex -d > foo.dvi
  289. </verb></tscreen>
  290.  
  291. If you want to produce plain ASCII, through <tt/groff/, use the command:
  292. <tscreen><verb>
  293. $ format -Tnroff foo | qroff > foo.txt
  294. </verb></tscreen>
  295. Note that I have tailored the <tt/groff/ conversion for plain ASCII output.
  296. (That is, I've removed page headers, page numbers, changed the margins,
  297. and so on.) With some hacking you can produce PostScript and DVI from the 
  298. <tt/groff/ resulting from <tt/format/, but I suggest that you use LaTeX
  299. for that instead.
  300.  
  301. If you want to produce HTML, the procedure is a bit more complicated,
  302. because of cross-references. Here's an example:
  303. <tscreen><verb>
  304. $ format -Thtml foo.sgml | prehtml | fixref > tmp.html
  305. $ format -Thtml foo.sgml | prehtml >> tmp.html
  306. $ cat tmp.html | html2html foo > foo.html
  307. $ rm tmp.html
  308. </verb></tscreen>
  309. This will produce <tt>foo.html</tt>, as well as <tt>foo-1.html</tt>,
  310. <tt/foo-2.html/, and so on---one file for each section of the document.
  311. Run your WWW client on <tt>foo.html</tt>, which is the toplevel file.
  312. Also make sure that all of the HTML files corresponding to your document
  313. are in one directory, as they reference each other with local URLs. 
  314.  
  315. A good way to test this would be to run it on this file,
  316. <tt/guide.sgml/. 
  317.  
  318. If you just want to capture your errors from the SGML conversion,
  319. use something like
  320. <tscreen><verb>
  321. $ format -Tnroff foo > /dev/null
  322. </verb></tscreen>
  323.  
  324. <sect1>Development note
  325. <p>
  326.  
  327. The HTML conversion is, at this time, rudimentary but adequate. In the
  328. future there will be support for cross-references, navigation buttons, 
  329. external URLs, and the like. Something is better than nothing. :)
  330.  
  331. Also, if you'd like to help me implement a texinfo (or plain Info) 
  332. conversion for Linuxdoc-SGML, let me know! As with HTML we'll have to
  333. do some pre- and post-processing (which you supposedly shouldn't need with
  334. SGML, ah well), but that's not a big issue. 
  335.  
  336. <sect>Writing Documents with <tt/linuxdoc-sgml/
  337.  
  338. <p>
  339. For the most part, writing documents using the <tt/linuxdoc/ DTD is very
  340. simple, and somewhat like LaTeX. However, there are some caveats to watch
  341. out for. In this section I'll give an introduction on writing SGML docs.
  342. See the file <tt/example.sgml/ for an SGML example document (and tutorial)
  343. which you can use as a model when writing your own docs. Here I'm just going
  344. to discuss the various features of SGML, but the source is not very 
  345. readable as an example. Instead, print out the source (as well as the
  346. formatted output) for <tt/example.sgml/ so you have a real live case to
  347. refer to.
  348.  
  349. <sect1>Basic concepts
  350.  
  351. <p>
  352. Looking at the source of the example document, you'll notice right off
  353. that there are a number of ``tags'' marked within angle brackets
  354. (<tt><</tt> and <tt/>/). A tag simply specifies the beginning or end
  355. of an element, where an element is something like a section, a paragraph,
  356. a phrase of italicized text, an item in a list, and so on. Using a tag
  357. is like using a LaTeX command such as <tt>\item</tt> or 
  358. <tt>\section{...}</tt>.
  359.  
  360. As a simple example, to produce <bf>this boldfaced text</bf>, I typed
  361. <tscreen><verb>
  362. As a simple example, to produce <bf>this boldfaced text&etago;bf>, ...
  363. </verb></tscreen>
  364. in the source. <tt><bf></tt> begins the region of bold text, and
  365. <tt>&etago;bf></tt> ends it. Alternately, use can use the abbreviated form
  366. <tscreen><verb>
  367. As a simple example, to produce <bf/this boldfaced text/, ...
  368. </verb></tscreen>
  369. which encloses the bold text within slashes. (Of course, you'll need to
  370. use the long form if the enclosed text contains slashes, such as the
  371. case with UNIX filenames). 
  372.  
  373. There are other things to watch out with respect to special characters 
  374. (that's why you'll notice all of these bizarre-looking ampersand 
  375. expressions if you look at the source; I'll talk about those shortly).
  376.  
  377. In some cases, the end-tag for a particular element is optional. For
  378. example, to begin a section, you use the <tt><sect></tt> tag, 
  379. however, the end-tag for the section (which could appear at the end of
  380. the section body itself, not just after the name of the section!) 
  381. is optional and implied when you start another section of the same depth.
  382. In general you needn't worry about these details; just follow the model
  383. used in the tutorial (<tt/example.sgml/), and feel free to ask me if you 
  384. have any questions about the particulars.
  385.  
  386. <sect1>Special characters
  387.  
  388. <p>
  389. Obviously, the angle brackets are themselves special characters in the
  390. SGML source. There are others to watch out for. For example, let's say 
  391. that you wanted to type an expression with angle brackets around it,
  392. as so: <tt><foo></tt>. In order to get the left angle bracket, you
  393. must use the <tt>&lt</tt> element, which is a ``macro'' that expands
  394. to the actual left-bracket character. Therefore, in the source, I typed
  395. <tscreen><verb>
  396. angle brackets around it, as so: <tt>&ero;lt;foo>&etago;tt>.
  397. </verb></tscreen>
  398. Generally, something beginning with an ampersand is a special macro. For
  399. example, there's <tt/&percnt/ to produce <tt>%</tt>, 
  400. <tt/&verbar/ to produce <tt>|</tt>, and so on. For all 
  401. ``special characters'' there exist these ampersanded-entities to represent
  402. them. 
  403.  
  404. Usually, you don't need to use the ampersand macro to get a special
  405. character, however, in some cases it is necessary. The most commonly used
  406. are:
  407. <itemize>
  408. <item>Use <tt>&amp;</tt> for the ampersand (<tt>&</tt>), 
  409. <item>Use <tt>&lt;</tt> for a left bracket (<tt><</tt>),
  410. <item>Use <tt>&gt;</tt> for a right bracket (<tt>></tt>),
  411. <item>Use <tt>&etago;</tt> for a left bracket with a slash 
  412. (<tt>&etago;</tt>)
  413. <item>Use <tt>&dollar;</tt> for a dollar sign (<tt>$</tt>),
  414. <item>Use <tt>&num;</tt> for a hash (<tt>#</tt>),
  415. <item>Use <tt>&percnt;</tt> for a percent (<tt>%</tt>),
  416. <item>Use <tt>``</tt> and <tt>''</tt> for quotes, or use
  417.       <tt>&dquot</tt> for <tt>&dquot;</tt>.
  418. </itemize>
  419.  
  420. <sect1>Verbatim and code environments
  421.  
  422. <p>
  423. While we're on the subject of special characters, I might as well mention
  424. the verbatim ``environment'' used for including literal text in the output
  425. (with spaces and indentation preserved, and so on). The 
  426. <tt>verb</tt> element is used for this; it looks like the following:
  427. <tscreen><verb>
  428. <verb>
  429.   Some literal text to include as example output.
  430. &etago;verb>
  431. </verb></tscreen>
  432. The <tt>verb</tt> environment doesn't allow you to use <em/everything/
  433. within it literally. Specifically, you must do the following within
  434. <tt/verb/ environments.
  435. <itemize>
  436. <item>Use <tt>&ero;</tt> to get an ampersand, 
  437. <item>Use <tt>&etago;</tt> to get <tt>&etago;</tt>,
  438. <item>Don't use <tt>\end{verbatim}</tt> within a <tt>verb</tt>
  439. environment, as this is what LaTeX uses to end the <tt>verbatim</tt> 
  440. environment. (In the future, it should be possible to hide the underlying
  441. text formatter entirely, but the parser doesn't support this feature yet.) 
  442. </itemize>
  443. The <tt>code</tt> environment is much just like the <tt/verb/ environment,
  444. except that horizontal rules are added to the surrounding text, as so:
  445. <code>
  446. Here is an example code environment.
  447. </code>
  448.  
  449. You should use the <tt/tscreen/ environment around any <tt/verb/ environments,
  450. as so:
  451. <tscreen><verb>
  452. <tscreen><verb>
  453. Here is some example text. 
  454. &etago;verb>&etago;tscreen>
  455. </verb></tscreen>
  456. <tt/tscreen/ is an envionment that simply indents the text and sets the 
  457. sets the default font to <tt/tt/. This makes examples look much nicer, both
  458. in the LaTeX and plain ASCII versions. You can use <tt/tscreen/
  459. without <tt/verb/, however, if you use any special characters in your 
  460. example you'll need to use both of them. <tt/tscreen/ does nothing to 
  461. special characters. See <tt/example.sgml/ for examples.
  462.  
  463. The <tt/quote/ environment is like <tt/tscreen/, except that it does
  464. not set the default font to <tt/tt/. So, you can use <tt/quote/ for
  465. non-computer-interaction quotes, as in:
  466. <tscreen><verb>
  467. <quote>
  468. Here is some text to be indented, as in a quote.
  469. &etago;quote>
  470. </verb></tscreen>
  471. which will generate:
  472. <quote>
  473. Here is some text to be indented, as in a quote.
  474. </quote>
  475.  
  476. <sect1>Overall document structure
  477.  
  478. <p>
  479. Before we get too in-depth with details, I'm going to describe the
  480. overall structure of a document as defined by the <tt/linuxdoc/ DTD.
  481. Look at <tt/example.sgml/ for a good example of how a document is set up.
  482.  
  483. <sect2>The preamble
  484.  
  485. <p>In the document ``preamble'' you set up things such as the title
  486. information and document style. For a Linux HOWTO document this should
  487. look like:
  488. <tscreen><verb>
  489. <!doctype linuxdoc system>
  490.  
  491. <article>
  492.  
  493. <title>The Linux Food-Processing HOWTO
  494. <author>Norbert Ebersol, <tt/norbert@foo.com/
  495. <date>v1.0, 9 March 1994
  496. <abstract>
  497. This document describes how to connect your Linux machine to a food-processor
  498. for dicing vegetables.
  499. &etago;abstract>
  500.  
  501. <toc>
  502. </verb></tscreen>
  503.  
  504. The elements should go more or less in this order. The first line tells
  505. the SGML parser to use the <tt/linuxdoc/ DTD. The <tt><article></tt>
  506. tag forces the document to use the ``article'' document style. (The 
  507. original QWERTZ DTD defines ``report'' and ``book'' as well; I haven't
  508. tweaked these for use with <tt/linuxdoc-sgml/. Just use <tt/article/ for
  509. you SGML docs, for now.)
  510.  
  511. The <tt/title/, <tt/author/, and <tt/date/ tags should be obvious; in the
  512. <tt>date</tt> tag include the version number and last modification time of
  513. the document.
  514.  
  515. Thr <tt/abstract/ tag sets up the text to be printed at the top of the
  516. document, <em/before/ the table of contents. If you're not going to
  517. include a table of contents (the <tt/toc/ tag), you probably don't
  518. need an <tt/abstract/. I suggest that all Linux HOWTOs use this same format
  519. for the preamble, so that the title, abstract, and table of contents are
  520. all there and look the same. 
  521.  
  522. <sect2>Sectioning and paragraphs
  523.  
  524. <p>After the preamble, you're ready to dive into the document. The following
  525. sectioning commands are available:
  526. <itemize>
  527. <item><tt/sect/: For top-level sections (i.e. 1, 2, and so on.) 
  528. <item><tt/sect1/: For second-level subsections (i.e. 1.1, 1.2, and so on.)
  529. <item><tt/sect2/: For third-level subsubsections.
  530. <item><tt/sect3/: For fourth-level subsubsubsections.
  531. <item><tt/sect4/: For fifth-level subsubsubsubsections.
  532. </itemize>
  533. These are roughly equivalent to their LaTeX counterparts <tt/section/,
  534. <tt/subsection/, and so on.
  535.  
  536. After the <tt/sect/ (or <tt/sect1/, <tt/sect2/, etc.) tag comes the
  537. name of the section. For example, at the top of this document, after
  538. the preamble, comes the tag:
  539. <tscreen><verb>
  540. <sect>Introduction
  541. </verb></tscreen>
  542. And at the beginning of this section (Sectioning and paragraphs), there
  543. is the tag:
  544. <tscreen><verb>
  545. <sect2>Sectioning and paragraphs
  546. </verb></tscreen>
  547.  
  548. After the section tag, you begin the body of the section. However, you
  549. must start the body with a <tt><p></tt> tag, as so:
  550. <tscreen><verb>
  551. <sect>Introduction
  552.  
  553. <p>
  554. This is a user's guide to the <tt/linuxdoc-sgml/ document processing...
  555. </verb></tscreen>
  556. This is to tell the parser that you're done with the section title
  557. and are ready to begin the body. Thereafter, new paragraphs are started
  558. with a blank line (just as you would do in TeX). For example,
  559. <tscreen><verb>
  560. Here is the end of the first paragraph.
  561.  
  562. And we start a new paragraph here.
  563. </verb></tscreen>
  564. There is no reason to use <tt><p></tt> tags at the beginning of
  565. every paragraph; only at the beginning of the first paragraph after
  566. a sectioning command.
  567.  
  568. <sect2>Ending the document
  569.  
  570. <p>At the end of the document, you must use the tag:
  571. <tscreen><verb>
  572. &etago;article>
  573. </verb></tscreen>
  574.  
  575. to tell the parser that you're done with the <tt/article/ element (which
  576. embodies the entire document). 
  577.  
  578. </sect2>
  579. <sect1><heading><label id="cross-ref">Cross-references</>
  580.  
  581. <p>Now we're going to move onto other features of the system. 
  582. Cross-references are easy. For example, if you want to make a
  583. cross-reference to a certain section, you need to label that section
  584. as so:
  585. <tscreen><verb>
  586. <sect1><heading><label id="sec-intro">Introduction&etago;>
  587. </verb></tscreen>
  588. You can then refer to that section somewhere in the text using the
  589. expression:
  590. <tscreen><verb>
  591. See section <ref id="sec-intro" name="Introduction"> for an introduction.
  592. </verb></tscreen>
  593. This will replace the <tt/ref/ tag with the section number labelled
  594. as <tt/sec-intro/. The <tt/name/ argument to <tt/ref/ is necessary for
  595. <tt/nroff/ and HTML translations (at the moment). The <tt/nroff/
  596. macro set used by Linuxdoc-SGML does not currently support cross-references,
  597. and it's often nice to refer to a section by name instead of number. 
  598.  
  599. For example, this section is <ref id="cross-ref" name="Cross-references">.
  600.  
  601. There is also a <tt/url/ element for Universal Resource Locators, or
  602. URLs, used on the World Wide Web. This element should be used to refer
  603. to other documents, files available for FTP, and so forth. For
  604. example,
  605. <tscreen><verb>
  606. You can get the Linux HOWTO documents from 
  607. <url url="http://sunsite.unc.edu/mdw/linux.html" 
  608.      name="the Linux Documentation Project home page">.
  609. </verb></tscreen>
  610. The <tt/url/ argument specifies the actual URL itself. A link to the
  611. URL in question will be automatically added to the HTML document.
  612. The optional <tt/name/ argument specifies the text that should be anchored to
  613. the URL (for HTML conversion) or named as the description of the
  614. URL (for LaTeX and <tt/nroff/). If no <tt/name/ argument is given, the
  615. URL itself will be used.
  616.  
  617. For example, you can get the Linuxdoc-SGML package from
  618. <url url="ftp://ftp.cs.cornell.edu/mdw/linuxdoc-sgml-1.1.tar.gz">.
  619.  
  620. <sect1>Fonts
  621.  
  622. <p>Essentially, the same fonts supported by LaTeX are supported
  623. by <tt/linuxdoc-sgml/. Note, however, that the conversion to 
  624. plain ASCII (through <tt/groff/) does away with the font 
  625. information---I might hack up plain-ASCII representations of the
  626. various fonts if the need arises. So, you should use fonts 
  627. as much as possible, for the benefit of the conversion to LaTeX.
  628. But don't depend on the fonts to get a point across in the plain
  629. ASCII version. 
  630.  
  631. In particular, the <tt/tt/ tag described above can be used to
  632. get constant-width ``typewriter'' font which should be used for
  633. all e-mail addresses, machine names, filenames, and so on. 
  634. Example:
  635. <tscreen><verb>
  636. Here is some <tt>typewriter text&etago;tt> to be included in the document.
  637. </verb></tscreen>
  638. Equivalently:
  639. <tscreen><verb>
  640. Here is some <tt/typewriter text/ to be included in the document.
  641. </verb></tscreen>
  642. Remember that you can only use this abbreviated form if the enclosed
  643. text doesn't contain slashes.
  644.  
  645. Other fonts can be achieved with <tt/bf/ for <bf/boldface/ and <tt/em/ 
  646. for <tt/italics/. Several other fonts are supported as well, but
  647. I don't suggest you use them, because we'll be converting these
  648. documents to other formats such as HTML which may not support them.
  649. Boldface, typewriter, and italics should be all that you need.
  650.  
  651. <sect1>Lists
  652.  
  653. <p>There are various kinds of supported lists. They are:
  654. <itemize>
  655. <item><tt/itemize/ for bulleted lists such as this one.
  656. <item><tt/enum/ for numbered lists.
  657. <item><tt/descrip/ for ``descriptive'' lists. 
  658. </itemize>
  659. Each item in an <tt/itemize/ or <tt/enum/ list must be marked
  660. with an <tt/item/ tag. Items in a <tt/descrip/ are marked with <tt/tag/.
  661. For example,
  662. <tscreen><verb>
  663. <itemize>
  664. <item>Here is an item.
  665. <item>Here is a second item.
  666. &etago;itemize>
  667. </verb></tscreen>
  668. Looks like this:
  669. <itemize>
  670. <item>Here is an item.
  671. <item>Here is a second item.
  672. </itemize>
  673. Or, for an <tt/enum/,
  674. <tscreen><verb>
  675. <enum>
  676. <item>Here is the first item.
  677. <item>Here is the second item.
  678. &etago;enum>
  679. </verb></tscreen>
  680. You get the idea. Lists can be nested as well; see the example document
  681. for details.
  682.  
  683. A <tt/descrip/ list is slightly different, and slightly ugly, but
  684. you might want to use it for some situations:
  685. <tscreen><verb>
  686. <descrip>
  687. <tag/Gnats./ Annoying little bugs that fly into your cooling fan.
  688. <tag/Gnus./ Annoying little bugs that run on your CPU.
  689. &etago;descrip>
  690. </verb></tscreen>
  691. ends up looking like:
  692. <descrip>
  693. <tag/Gnats./ Annoying little bugs that fly into your cooling fan.
  694. <tag/Gnus./ Annoying little bugs that run on your CPU.
  695. </descrip>
  696.  
  697. <sect1>Miscellany
  698.  
  699. <p>
  700. There are various other esoteric features in the system as well, most
  701. of which you probably won't use. If you're curious, read the QWERTZ
  702. User's Guide (from <tt/ftp.cs.cornell.edu/ in <tt>pub/mdw/SGML</tt>).
  703. QWERTZ (and hence, <tt/linuxdoc/) supports many features such as 
  704. mathematical formulae, tables, figures, and so forth. I don't recommend
  705. using most of these features in the Linux HOWTOs because they won't render
  706. well in plain ASCII. If you'd like to write general documentation in
  707. SGML, I suggest using the original QWERTZ DTD instead of the hacked-up
  708. <tt/linuxdoc/ DTD, which I've modified for use particularly by the Linux
  709. HOWTOs and other documentation. 
  710.  
  711. The bottom line is, <tt/linuxdoc-sgml/ supports many other features found
  712. in the QWERTZ DTD, but I haven't necessarily tweaked them to work well
  713. with <tt/linuxdoc-sgml/. If you encounter problems with any of them,
  714. please let me know.
  715.  
  716. <sect>The Linux HOWTO project
  717.  
  718. <p>How does this tie into writing HOWTOs? First of all, I'd like to see
  719. everyone eventually convert their HOWTOs to SGML using this DTD. This has
  720. a number of advantages. First of all, it will allow you to just send me
  721. the SGML source, which I'll convert to plain ASCII, TeX, whatever, for
  722. posting and archiving. Also, it will give the HOWTOs a common look and feel;
  723. any changes that I make to the DTD will be reflected in all of the HOWTOs.
  724.  
  725. I have set up the <tt/linuxdoc/ DTD to have a certain look and feel.
  726. If you want your document to look differently, please let me know, because
  727. I'll need to make those changes in the DTD itself. That is, <em/do not/
  728. modify your version of the DTD or replacement files to get other features
  729. in the system. We all must use the same DTD and replacement files or 
  730. this whole system will break down. If you find bugs in it, or have suggestions
  731. for how we can change thing or add/modify features, let me know. I'll be
  732. more than happy to accomodate you.
  733.  
  734. </article>
  735.